Compendium Deluxe 2

home *** CD-ROM | disk | FTP | other *** search

/ Compendium Deluxe 2 / LSD and 17bit Compendium Deluxe - Volume II.iso / a / prog / amigae / autobuild11.lha / AutoBuild / AutoBuild.doc next >

Wrap

Text File | 1994-11-27 | 14.0 KB | 307 lines

***************************** * Autobuild v1.1 * * © 1994 Jan Hendrik Schulz * ***************************** Indroduction ~~~~~~~~~~~~ What is autobuild? Autobuild is an automatic build tool for AmigE. It can do the same think like the build tool that came with AmigaE v3 if it is used to build programms which are splitted over several modules, but it does it automaticly. That meens, you need no .build-file to define the dependencies etc. Additionaly if you use Mac2E you can (must) define the macrofiles that are needed with a new keyword (MACROS) directly in the source. And you can define whole macros in the source,too. History ~~~~~~~ v1.0 - First public release v1.1 - Sources without PROC and EXPORT causing no error anymore. - v1.0 doesn't noticed a failing EC or Mac2E sometimes and doesn't stop. I hope, this bug is fixed now. (- No important changes in this doc-file. You don't need to read this docs, if you allready had read the v1.0 docs.) Why using autobuild and not build? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you are writing a big program and splitt the source into several modules, you have to change the .build-file everytime when you introduce a new module, or if a source after some changes needs other modules (or macrofiles, if you use Mac2E). With autobuild, if you have changed the MODULE information in the source, autobuild sees automaticly the new dependence and acts accordingly. And if you use Mac2E and your source needs another macrofile, it's easier (I think) to add the name of this macrofile into the source and not into an extra .build-file. Or if you need a (simple) macro only with one source, with autobuild you can define it directly in this source if you want. You don't have to create an extra macrofile for it (autobuild does this for you). And last but not least, unlike build, autobuild sees circular dependen- cies between the files. And if you call it with FORCE, every file is still builded only once! Requirements ~~~~~~~~~~~~ To use autobuild you need Kickstart 2.04 or better, AmigaE and maybe Mac2E if you want to use macros. How to use autobuild? ~~~~~~~~~~~~~~~~~~~~~ Autobuild must be called from the shell and it has the following syntax: TARGET,FORCE=F/S,PRIVATONLY=PO/S,QUIET=Q/S,ECOPTS=EO/K,ECPATH=EP/K, MACOPTS=MO/K,MACPATH=MP/K,MACQUIET=MQ/S TARGET is the name of the file that should be build. (Without the .m if it is a module!) FORCE tells autobuild to build all files, even if they are allready uptodate. (Even with FORCE, every file is build only once!) PRIVATONLY Normaly autobuild compares the filedate of EVERY used module and macrofile with the filedate of the target to find out, if the target is up to date (newer). If you use PRIVATONLY, only the private modules and macrofiles (those which names starting with a *) are testet and not those in EMODULES: and EMACROS: QUIET Only error-messages (and the output of EC and Mac2E) are printed. ECOPTS here you can give additional arguments for the EC-call. You should write doublequotes around them! Autobuild calls EC like this: EC <file> <ecopts> Example: autobuild target ECOPTS "QUIET" ECPATH You can tell autobuild where to find EC and than autobuild copies EC to RAM:EC (if needed) and uses RAM:EC instead of EC. Example: autobuild target ECPATH "Work:AmigaE/Bin/EC" MACOPTS Like ECOPTS but for the Mac2E call. Autobuild calls Mac2E like this: Mac2E <source.em> <source.e> <macopts> WITH <macrofiles> MACPATH Like ECPATH but for Mac2E. MACQUIET tells autobuild to redirect the output of Mac2E to a temporary file (t:mac2eout). This file is only (but automaticly) shown if the Mac2E-call wasn't successfull. The .autobuild file ~~~~~~~~~~~~~~~~~~~ To make the autobuild call easier, autobuild looks for a file called ".autobuild" in the currend directory and if it exists, the first line of this file is passed through ReadArgs() with the template above. So normaly you can execute autobuild without any arguments. If you use arguments and additionaly there is a .autobuild-file, both are mixed like this: TARGET, ECOPTS, ECPATH, MACOPTS and MACPATH: If you give them with the commandline, the corresponding .autobuild setting is ignored. FORCE, PRIVATEONLY, QUIET and MACQUIET: The commandline and the .autobuild-settings are Eor()ed. How does autobuild work? ~~~~~~~~~~~~~~~~~~~~~~~~ To see, how autobuild works, I think it's the best way to show you how the most important PROC of autobuild - build() - works. If you call autobuild e.g. with 'autobuild abc' than main() calls after some initial work build() with 'abc' as target. And build() works like this: *-----------------------* | PROC build(target) | *-----------+-----------* | ?-----------+-----------? +--NO--+ Exists 'target.em' ? +--YES--+ | ?-----------------------? | | | +--------------+--------------+ +--------------+--------------+ | Look into 'target.e' to see | | Look into 'target.em' to see| | which emodules are used by | | which emodules and which | | this source. | | macrofiles are used, and to | +--------------+--------------+ | create, if necessary, a tmp.| | | macrofile from the macrodefs| | | in the source. | | +--------------+--------------+ | | | ?--------------+--------------? | +---NO--+ Exists 'target.e' ? | | | ?--------------+--------------? | | | YES | | ?--------------+--------------? | | | Is 'target.em' newer than | | +--YES--+ 'target.e' ? | | | ?--------------+--------------? | | | NO | | ?--------------+--------------? | | | Is at least one of the used | | +--YES--+ macrofiles newer than | | | | 'target' (or 'target.m') ? | | \ ?--------------+--------------? | \ | NO | +--------------+--------------+ | | | Call Mac2E to build an up | | | | to date 'target.e'-file | | | +--------------+--------------+ | | | | +----------------+ | +-----------------+ \|/ +--------------+--------------+ | Call build() for every used | | privat emodule to make them | | up to date if necessary | +--------------+--------------+ | ?--------------+--------------? | Exists 'target' | +---NO--+ (or 'target.m') ? | | ?--------------+--------------? | | YES | ?--------------+--------------? | | Is 'target.e' newer than | +--YES--+ 'target' (or 'target.m') ? | | ?--------------+--------------? | | NO | ?--------------+--------------? | | Is at least one of the used | +--YES--+ emodules newer than 'target'| \ | (or 'target.m') ? | \ ?--------------+--------------? \ | NO +-------------+-------------+ | | Call EC to build an up to | | | date 'target'-file | | | (or 'target.m'-file ) | | +-------------+-------------+ | | | +----------------+ | \| *---+---* | END | *-------* The above shoud only give an idea what the PROC build() does. The real PROC build() works a little bit different! It has some lists in memory to build every file only once, and to look for the filedate of a file only once for example, but the result is the same. How to define macrofiles and macros? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ First, if you have a source with macros, it's name must end with '.em'! Autobuild then calls Mac2E to build the '.e'-file. To define which macro- files should be used, there is the new keyword MACROS. Use this keyword like the AmigaE keyword MODULE: Write MACROS 'abc.pma' to use the macrofile 'EMACROS:abc.pma'. And write MACROS '*abc.pma' to use the macrofile '<sourcedir>abc.pma'. Example: MACROS 'abc.pma', '*xyz.pma', -> You can use a comment here... /* ... or here ... */ '*macros.ma' -> ...or here! To define a macro directly in the source, autobuild uses a more E-like syntax than Mac2E. There are two ways: MACRO name IS body MACRO name body ENDMACRO To see, how to use this, now some examples on the left side and the Mac2E version that is builded by autobuild for the Mac2E call on the right side: | MACRO test IS 10 |#define test 10 | MACRO abc(x,y,z) IS a+b+c -> comment |#define abc(x,y,z) a+b+c | MACRO xyz IS /* comment |#define xyz XYZ */ XYZ | | MACRO blah |#define blah\ first line -> with comment |first line\ abc /* comment */ xyz |abc\ LAST LINE |xyz\ -> empty line |LAST LINE ENDMACRO | Some important infos! ~~~~~~~~~~~~~~~~~~~~~ - All the MACRO and MACROS stuff above must be in comments to have no problems with the E-compiler. Simply put a line with /* before it and a line with */ behind it. Example: /* MACROS 'test.pma' MACRO abc IS xyz */ - Autobuild reads the source only until it finds the first PROC or EXPORT keyword to make things faster. Is there no PROC or EXPORT, the whole file is read. - To make autobuild not to complicate, the keywords MODULE, MACRO, MACROS, PROC and EXPORT must be on the beginning of the line! (No leading spaces or tabs.) If they are not at the beginning of the line, autobuild doesn't see them! On the other hand, if you use the keyword in other situations (e.g. MODULE after an OPT), make shure that it is NOT at the beginning of the line to make it invisible for autobuild! Copyright and Author ~~~~~~~~~~~~~~~~~~~~ Autobuild is (c) copyright 1994 Jan Hendrik Schulz Redistributing autobuild is allowed, as long as all files are included and unchanged, and as long as no profit (direct or indirect) is made by distributing autobuild! Autobuild is giftware, if you use it, send me something usefull (money, an Amiga 4000 or at least a postcard or an e-mail). [ After the first release I got only ONE e-mail (thanks Lionel). If really nobody else uses autobuild, I could send the next version directly to him! So, if you use it, send me an e-mail, a postcard or something else! ] My address: Jan Hendrik Schulz Reinhard-Raffalt-Str. 41 94036 Passau Germany Internet: schulzj@fmi.uni-passau.de Disclaimer ~~~~~~~~~~ THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDER AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.